package org.dreamwork.jasmine2.engine;

import org.dreamwork.jasmine2.events.EventException;
import org.dreamwork.jasmine2.events.IDataBindListener;

/**
 * 可绑定对象
 *
 * <p>可绑定对象表明了该对象可被进行数据绑定，通过 dataSource 和 valueField 属性进行统一的数据读取操作
 * <p>可绑定对象通过向该对象内添加数据绑定监听器(#org.dreamwork.jasmine2.events.IDataBindListener)进行数据绑定处理
 *
 * Created by IntelliJ IDEA.
 * User: seth
 * Date: 2009-1-30
 * Time: 22:53:21
 */
public interface IBindable {
    /**
     * 设置数据源.
     * <p>任意 java 对象都可作为数据源，其解析方式由具体实现来完成
     * @param dataSource 数据源
     */
    void setDataSource (Object dataSource);

    /**
     * 设置数据成员名称
     * @param dataMember 数据成员名称
     */
    void setDataMember (String dataMember);

    /**
     * 设置数据字段名称
     * <p>数据字段表明该绑定的数据取自于 dataSource 属性的 fieldName 属性。该属性的使用规则由具体实现来定义
     * @param fieldName
     */
    void setValueField (String fieldName);

    /**
     * 进行数据绑定
     * @throws Throwable 任何异常
     */
    void dataBind () throws Throwable;

    /**
     * 添加数据绑定监听器
     * @param listener 数据绑定监听器
     */
    void addDataBindEvent (IDataBindListener listener);

    /**
     * 删除数据绑定监听器
     * @param listener 数据绑定监听器
     */
    void removeDataBindEvent (IDataBindListener listener);

    /**
     * 获取所有有效的数据绑定接听器数组
     * @return 所有数据绑定监听器
     */
    IDataBindListener[] getDataBindEvents ();

    /**
     * 调用数据监听器的事件
     * @throws EventException 事件异常
     */
    void fireDataBindEvents () throws EventException;
}
